Introduction
------------------------------------------------------------------------------

  This Symbian^3 C++ code example provides two sample ECom plugin projects for
  implementing NFC (Near Field Communication) External Content Handlers.

  The subdirectories "example" and "template" contain two implementations of an
  NFC External Content Handler plugin. Both projects produce an identically
  named plugin DLL and use the same UID, hence one implementation can be
  replaced with the other by simply installing it over an existing installation.

  The plugin registers itself as the handler for the external NDEF record type
  "urn:nfc:ext:www.developer.nokia.com:example".

  The "template" project is a minimal implementation, i.e. it constitutes a
  fully working content handler, but the implementation itself is empty, nothing
  is done with the intercepted NDEF messages.

  The plugin in the "example" project is identical to the "template"
  implementation in all other respects, except that it contains an active object
  that handles NDEF messages with recognized NDEF records by passing the entire
  message to a Qt Quick application. The message transferred from the plugin to
  the application process using global shared memory.

Compilation and installation
------------------------------------------------------------------------------

  The supplied projects have been tested using Nokia Qt SDK 1.1.3 and the
  Qt 4.7.4 for Symbian Belle target.

  To compile the example plugin and application, import the example.pro located
  in the example directory into Qt Creator. Select the "Qt 4.7.4 for Symbian Belle
  (Qt SDK) debug" and "Qt 4.7.4 for Symbian Belle (Qt SDK) release" targets.
  Once the project has been imported, select "Build All" from the "Build" menu
  to compile both the plugin and the application.

  Note that as the plugin is a native Symbian ECom plugin project (meaning there
  is no qmake project file, other than the one that just includes the Symbian MMP
  project file), no installation package is automatically created during
  compilation. To create an installable SISX package for the plugin follow the
  "makesis" and "signsis" instructions given below for command line compilation.

  Once the plugin is compiled and installed you can install and run the application
  directly from within Qt Creator as you would any other Symbian Qt application.

  The plugin projects can also be compiled from the command line using the Symbian
  toolchain. Select "Qt SDK" > "Symbian Belle Qt 4.7.4" > "Qt 4.7.4 for Symbian
  Belle Command Prompt" from the Start menu to open the command prompt.

  Navigate to the directory where you unpacked the project source files. Starting
  from the project root directory (the directory containing this readme.txt file),
  use the following commands to compile and construct an installation package for
  the "template" project:

    cd template\group
    sbs --config=arm.v5.urel.gcce4_4_1
    cd ..\sis
    makesis nfccontenthandlerplugin.pkg
    signsis nfccontenthandlerplugin.sis nfccontenthandlerplugin.sisx developer.cer developer.key

  The commands above assume that you are using the Symbian Build System v2 and
  the GCCE 4.4.1 compiler, and that the files developer.cer and developer.key
  are your Open Signed Offline developer certificate and private key,
  respectively.

  Note that content handler plugins require the System Capabilities "SwEvent",
  "ReadDeviceData" and "WriteDeviceData". These capabilities are not user
  grantable and hence the generated SIS package will not be installable if
  signed with a self-signed certificate. A Symbian Signed developer certificate
  must be used to sign the package.

Application Usage
------------------------------------------------------------------------------

  The demo application nfccontenthandlerapplication.exe has two views, one for
  displaying the contents of NDEF messages read from tags, and one for writing
  NDEF messages with records of the required external type
  "urn:nfc:ext:www.developer.nokia.com:example". A record of this type written
  by the application contains a random number from 0000 to 9999 as its payload.
  You can switch between the two views by flicking up and down.

  When the application is started, the tag reader view is presented. The reader
  view can be identifier by a green background and the "reader" text at the top
  of the screen. The middle of the screen shows the record type and a value
  read from the tag. If no tags have been read, the view shows a random number.

  Touching a tag reads it. If the tag contains an NDEF message with a record of
  the expected type, the number contained in the record is displayed. For unknown
  record types "target detected", "tag read" and "target lost" messages are shown
  at the top of the screen, but the number is not updated.

  Tapping the number generates a new random value. You can use this to verify
  that a value was indeed read from a tag by changing the value shown and
  re-reading the tag.

  Flicking up reveals the "writer" view with a red background. In this view
  touching a tag writes an NDEF message containing the number shown to the tag.
  Tap the number to randomize the value and write different values to tags.

  Long tapping anywhere except on the number exits the demo application.

  Once you have some written some NFC tags with different values you can verify
  the functionality of the content handler plugin. The plugin intercepts messages
  containing records of the type "urn:nfc:ext:www.developer.nokia.com:example"
  even if the application is not running.

  Exit the application an touch a tag you wrote with the application. The plugin
  will read the entire NDEF message, store it in shared memory and start the
  application. When started, the application reads the shared memory to display
  the message previously read by the plugin.

  Tap the number to change the value to something else than the number read from
  the tag. Press the home key to return to the home screen, and to send the
  application to the background without exiting it.

  Now touch the tag again. The application will be brought to the foreground and
  it will again show the number read from the tag that was just touched.

Files with Placeholder Values
------------------------------------------------------------------------------

  The "template" project provides an empty stub implementation for a content
  handler plugin. When implementing a plugin of your own, in addition to
  changing the file and content handler class names, the following files in the
  "template" project contain values or names that should be modified to match
  the naming of your project:

  data\nfccontenthandlerplugin.rss

  * line 44, display_name = "...". the display_name is not visible on the user
    interface, but should still be a value set by the implementer of the plugin.
  * line 45, default_data = "...". the record type (or types) processed by this
    content handler implementation. You can specify more than one record type by
    separating the types with two pipe characters, e.g.

    default_data = "urn:nfc:ext:www.developer.nokia.com:type1||urn:nfc:ext:www.developer.nokia.com:type2".

  group\nfccontenthandlerplugin.mmp

  * line 24, TARGET. The name of the plugin DLL file. Note that it is very
    important that the DLL file be uniquely named, as on Symbian devices all
    binaries are placed in the same directory. Having two dynamic link
    libraries, e.g. two unrelated content handler plugins, with identical file
    names leads to obscure and hard to debug issues.
  * lines 45-46, RESOURCE. The source and destination file names of the plugin
    registration resource file. Similarly to the TARGET file name above, these
    should be unique. Generally it is good practice to name the registration
    resource file after the DLL file, only changing the file name suffixes to
    .rss for the source and .rsc for the compiled resource.

  inc\constants.hrh

  * line 21, KContentHandlerPluginDllUid. UID3 for the plugin DLL.
  * line 24, KContentHandlerImplementationUid. The UID of the NFC External 
    Content Handler interface implementation, in effect the "UID", if you will,
    of the CContentHandler class.

  sis\nfccontenthandlerplugin.pkg

  * line 45, the standard SIS file header. This contains both the name of the
    package as shown by the installer during installation as well as the UID3 of
    the plugin DLL (the same value that was defined for the constant
    KContentHandlerPluginDllUid in the file constants.hrh).
  * lines 65-66, paths of the files to include in the installation package.
    These should be changed to reflect both your Qt SDK installation (the source
    paths) and the names of the plugin DLL and resource files defined in the MMP
    file.

Version History
------------------------------------------------------------------------------

2011-May-10 10:01 UTC+03:00  Initial version.
2011-May-11 13:40 UTC+03:00  Added description for the "example" project.
2011-Jun-06 10:43 UTC+03:00  Clarified project and placeholder value descriptions.
2011-Jun-09 10:28 UTC+03:00  Fixed a potential memory leak caused by corrupt messages.
2011-Jun-14 13:47 UTC+03:00  Highlighted the importance of unique DLL names.
2011-Oct-17 11:14 UTC+03:00  Added application startup example plugin.
